---
sidebar_label: Plugin Architecture
description: Learn about OpenBao's plugin architecture.
---

# External plugin architecture

OpenBao's external plugins are completely separate, standalone applications that OpenBao
executes and communicates with over RPC. This means the plugin process does not
share the same memory space as OpenBao and therefore can only access the
interfaces and arguments given to it. This also means a crash in a plugin cannot
crash the entirety of OpenBao.

It is possible to enable a custom plugin with a name that's identical to a
built-in plugin. In such a situation, OpenBao will always choose the custom plugin
when enabling it.

## External plugin lifecycle

OpenBao external plugins are long-running processes that remain running once they are
spawned by OpenBao, the parent process. Plugin processes can be started by OpenBao's
active node. Additionally, there are cases where plugin processes may be
terminated by OpenBao. These cases include, but are not limited to:

- OpenBao active node step-down
- OpenBao barrier seal
- OpenBao graceful shutdown
- Disabling a Secrets Engine or Auth method that uses external plugins
- Database configured connection deletion
- Database configured connection update
- Database configured connection reset request
- Database root credentials rotation
- WAL Rollback from a previously failed root credentials rotation operation

The lifecycle of plugin processes are managed automatically by OpenBao.
Termination of these processes are typical in certain scenarios, such as the
ones listed above. OpenBao will start plugin processes when they are enabled. A
plugin process may be started or terminated through other internal processes
within OpenBao as well. Since OpenBao manages and tracks the lifecycle of its
plugins, these processes should not be terminated by anything other than OpenBao.
If a plugin process is shutdown out-of-band, the plugin process will be lazily
loaded when a request that requires the plugin is received by OpenBao.

## Plugin communication

OpenBao communicates with external plugins over RPC. To secure this
communication, OpenBao creates a mutually authenticated TLS connection with the
plugin's RPC server. Plugins make use of the AutoMTLS feature of
[go-plugin](https://www.github.com/hashicorp/go-plugin) which will
automatically negotiate mutual TLS for transport authentication.

The [`api_addr`](/docs/configuration#api_addr) must be set in order for the
plugin process to establish communication with the OpenBao server during mount
time. If the storage backend has HA enabled and supports automatic host address
detection, OpenBao will automatically attempt to determine the `api_addr` as
well.

## Plugin registration

An important consideration of OpenBao's plugin system is to ensure the plugin
invoked by OpenBao is authentic and maintains integrity. There are two components
that an OpenBao operator needs to configure before external plugins can be run- the
plugin directory and the plugin catalog entry.

### Plugin directory

The plugin directory is a configuration option of OpenBao and can be specified in
the [configuration file](/docs/configuration).
This setting specifies a directory in which all plugin binaries must live;
_this value cannot be a symbolic link_. A plugin
cannot be added to OpenBao unless it exists in the plugin directory. There is no
default for this configuration option, and if it is not set, plugins cannot be
added to OpenBao.

@include 'plugin-file-permissions-check.mdx'

### Plugin catalog

The plugin catalog is OpenBao's list of approved plugins. The catalog is stored in
OpenBao's barrier and can only be updated by an OpenBao user with sudo permissions.
Upon adding a new plugin, the plugin name, SHA256 sum of the executable, and the
command that should be used to run the plugin must be provided. The catalog will
ensure the executable referenced in the command exists in the plugin
directory. When added to the catalog, the plugin is not automatically executed,
but becomes visible to backends and can be executed by them. For more
information on the plugin catalog please see the [Plugin Catalog API
docs](/api-docs/system/plugins-catalog).

An example of plugin registration in current versions of OpenBao:

```shell-session
$ bao plugin register -sha256=<SHA256 Hex value of the plugin binary> \
    secret \                  # type
    myplugin-database-plugin

Success! Registered plugin: myplugin-database-plugin
```

### Plugin execution

When a backend wants to run a plugin, it first looks up the plugin, by name, in
the catalog. It then checks the executable's SHA256 sum against the one
configured in the plugin catalog. Finally OpenBao runs the command configured in
the catalog, sending along the JWT formatted response wrapping token.

### Plugin upgrades

External plugins may be updated by registering and reloading them. More details
on the upgrade procedure can be found in
[Upgrading OpenBao Plugins](/docs/upgrading/plugins).

## Plugin multiplexing

To avoid spawning multiple plugin processes for mounts of the same type,
plugins can implement plugin multiplexing. This allows a single
plugin process to be used for multiple mounts of a given type. This single
process will be multiplexed across all OpenBao namespaces for mounts of this
type. Multiplexing a plugin does not affect the current behavior of existing
plugins.

To enable multiplexing, the plugin must be compiled with the `ServeMultiplex`
function call from OpenBao's respective `plugin` or `dbplugin` SDK packages. At
this time, there is no opt-out capability for plugins that implement
multiplexing. To use a non-multiplexed plugin, run an older version of the
plugin, i.e., the plugin calls the `Serve` function.

More resources on implementing plugin multiplexing:
* [Database secrets engines](/docs/secrets/databases/custom#serving-a-plugin-with-multiplexing)
* [Secrets engines and auth methods](/docs/plugins/plugin-development)
